useImperativeHandle is a React Hook that allows you to customize the value or methods exposed to a parent component when it uses a ref on a child component, effectively controlling the public API of the child.
By default, when a parent component attaches a ref to a child component, the parent gains access to the entire DOM node of the child's root element (or the full component instance for class components). useImperativeHandle allows you to override this and define a custom object that the parent can interact with, exposing only the specific methods or properties you choose[citation:3][citation:7]. This is often used as an "escape hatch" for imperative actions like focusing an input, triggering animations, or managing a video player, where a purely declarative approach is impractical[citation:1][citation:9].
The useImperativeHandle Hook must be used together with forwardRef. The forwardRef function is required because functional components do not accept a ref prop by default; it allows the parent's ref to be passed down to the child component, where useImperativeHandle can then modify it[citation:2][citation:7]. The Hook takes three arguments: the ref object received from forwardRef, a function that returns the object containing the methods you want to expose, and an optional dependencies array to control when the exposed object is recreated[citation:3].
Focus management: Triggering a focus on an input element inside a child component from a parent button[citation:3][citation:9].
Controlled animations: Starting or stopping a complex animation that is encapsulated within a child component.
Text selection: Programmatically selecting text inside a child's input or content-editable div.
Form validation: Calling a child form's internal
validatemethod from a parent submit button[citation:4][citation:6].Data fetching: Exposing a
refreshorresetmethod on a data grid or custom data-fetching component.
Avoid Overuse: React's documentation recommends using
refonly for imperative behaviors that cannot be expressed asprops. If something can be achieved declaratively (e.g., a modal'sisOpenstate), it should be done withpropsrather than imperative handles[citation:3][citation:7].Combined with
forwardRef:useImperativeHandleis always used withforwardRefin functional components. Therefvariable provided byforwardRefis the first parameter passed to the Hook[citation:2][citation:8].React 19 Simplification: Starting with React 19,
refis available as a standard prop, eliminating the need forforwardRefin many cases, although the core logic ofuseImperativeHandleremains unchanged[citation:3][citation:7].Dependencies: If your exposed methods depend on specific state or props, include those dependencies to ensure the ref handle is updated correctly[citation:5].